org.globalplatform
Class GPSystem

java.lang.Object
  org.globalplatform.GPSystem

public class GPSystem
extends java.lang.Object

The GPSystem class exposes a subset of the behavior of the OPEN to the outside world. The OPEN implements and enforces a Card Issuer's security policy relating to these services. This OPEN class provides functionality at the same level as the JCRE, i.e. the "system" context with special privileges. This class is composed of static methods visible to all applets importing the globalplatform package.

Since:

• export file version 1.0: initial version.
• export file version 1.1: new services and/or constants added.
• export file version 1.3: new services and/or constants added.
• export file version 1.5: new services and/or constants added.

Field Summary

static byte	APPLICATION_INSTALLED The current applet context is in the Life Cycle State of INSTALLED (0x03).
static byte	APPLICATION_LOCKED The current applet context is in the Life Cycle State of LOCKED (0x80).
static byte	APPLICATION_SELECTABLE The current applet context is in the Life Cycle State of SELECTABLE (0x07).
static byte	CARD_INITIALIZED The card is in the Life Cycle State of INITIALIZED (0x07).
static byte	CARD_LOCKED The card is in the Life Cycle State of CARD_LOCKED (0x7F).
static byte	CARD_OP_READY The card is in the Life Cycle State of OP_READY (0x01).
static byte	CARD_SECURED The card is in the Life Cycle State of SECURED (0x0F).
static byte	CARD_TERMINATED The card is in the Life Cycle State of TERMINATED (0xFF).
static byte	CVM_ETSI_PIN_APP_1 Indicates that the CVM interface required is the ETSI PIN App 1 (0x01).
static byte	CVM_ETSI_PIN_APP_2 Indicates that the CVM interface required is the ETSI PIN App 2 (0x02).
static byte	CVM_ETSI_PIN_APP_3 Indicates that the CVM interface required is the ETSI PIN App 3 (0x03).
static byte	CVM_ETSI_PIN_APP_4 Indicates that the CVM interface required is the ETSI PIN App 4 (0x04).
static byte	CVM_ETSI_PIN_APP_5 Indicates that the CVM interface required is the ETSI PIN App 5 (0x05).
static byte	CVM_ETSI_PIN_APP_6 Indicates that the CVM interface required is the ETSI PIN App 6 (0x06).
static byte	CVM_ETSI_PIN_APP_7 Indicates that the CVM interface required is the ETSI PIN App 7 (0x07).
static byte	CVM_ETSI_PIN_APP_8 Indicates that the CVM interface required is the ETSI PIN App 8 (0x08).
static byte	CVM_GLOBAL_PIN Indicates that the CVM interface required is a Global PIN (0x11).
static byte	FAMILY_AUHTORITY Deprecated. Use FAMILY_AUTHORITY instead.
static byte	FAMILY_AUTHORITY Indicates the family of the Authority Service Identifier (0x83).
static byte	FAMILY_CVM Indicates the family of the CVM Global Service Identifier (0x82).
static byte	FAMILY_HTTP_ADMINISTRATION Indicates the family of the HTTP Administration Service Identifier (0x84).
static byte	FAMILY_HTTP_REPORT Indicates the family of the HTTP Report Service Identifier (0x85).
static byte	FAMILY_SECURE_CHANNEL Indicates the family of the Secure Channel Global Service Identifier (0x81).
static byte	FAMILY_USSM Indicates the family of the USSM Global Service Identifier (0xA0).
static byte	GLOBAL_SERVICE_IDENTIFIER Indicates the generic Global Service Identifier (0x80).
static byte	SECURITY_DOMAIN_PERSONALIZED The Security Domain is in the Life Cycle State of PERSONALIZED (0x0F).

Constructor Summary

GPSystem()

Method Summary

static byte	getCardContentState() This method returns the Life Cycle State of the current applet context.
static byte	getCardState() This method returns the Life Cycle State of the card.
static CVM	getCVM(byte bCVMIdentifier) This method returns a handle to the CVM interface.
static GPRegistryEntry	getRegistryEntry(javacard.framework.AID reqAID) This method allows an Application (e.g. a CVM) to access the GP Registry entry of another Application.
static SecureChannel	getSecureChannel() This method returns a handle to the SecureChannel interface.
static GlobalService	getService(javacard.framework.AID serverAID, short sServiceName) This method returns a handle to the Global Services interface of a Global Services Application.
static boolean	lockCard() This method locks the card.
static boolean	setATRHistBytes(byte[] baBuffer, short sOffset, byte bLength) This method sets the historical bytes of the ATR (Answer To Reset) string.
static boolean	setCardContentState(byte bState) This method allows the application associated with the current applet context to change its state to an application specific life cycle state or to lock itself.
static boolean	terminateCard() This method terminates the card.

Methods inherited from class java.lang.Object

equals

Field Detail

APPLICATION_INSTALLED

public static final byte APPLICATION_INSTALLED

The current applet context is in the Life Cycle State of INSTALLED (0x03).

Note:

• The Life Cycle State INSTALLED could be indicated along with another application specific Life Cycle State, e.g. a value of (0x07) indicates that the applet has been made selectable.

See Also:

Constant Field Values

APPLICATION_SELECTABLE

public static final byte APPLICATION_SELECTABLE

The current applet context is in the Life Cycle State of SELECTABLE (0x07).

Note:

• The Life Cycle State SELECTABLE could be indicated along with another application specific Life Cycle State.

See Also:

Constant Field Values

SECURITY_DOMAIN_PERSONALIZED

public static final byte SECURITY_DOMAIN_PERSONALIZED

The Security Domain is in the Life Cycle State of PERSONALIZED (0x0F).

See Also:

Constant Field Values

CARD_OP_READY

public static final byte CARD_OP_READY

The card is in the Life Cycle State of OP_READY (0x01).

See Also:

Constant Field Values

CARD_INITIALIZED

public static final byte CARD_INITIALIZED

The card is in the Life Cycle State of INITIALIZED (0x07).

See Also:

Constant Field Values

CARD_SECURED

public static final byte CARD_SECURED

The card is in the Life Cycle State of SECURED (0x0F).

See Also:

Constant Field Values

CARD_LOCKED

public static final byte CARD_LOCKED

The card is in the Life Cycle State of CARD_LOCKED (0x7F).

See Also:

Constant Field Values

CARD_TERMINATED

public static final byte CARD_TERMINATED

The card is in the Life Cycle State of TERMINATED (0xFF).

See Also:

Constant Field Values

CVM_GLOBAL_PIN

public static final byte CVM_GLOBAL_PIN

Indicates that the CVM interface required is a Global PIN (0x11).

See Also:

Constant Field Values

CVM_ETSI_PIN_APP_1

public static final byte CVM_ETSI_PIN_APP_1

Indicates that the CVM interface required is the ETSI PIN App 1 (0x01).

Since:

export file version 1.5

See Also:

Constant Field Values

CVM_ETSI_PIN_APP_2

public static final byte CVM_ETSI_PIN_APP_2

Indicates that the CVM interface required is the ETSI PIN App 2 (0x02).

Since:

export file version 1.5

See Also:

Constant Field Values

CVM_ETSI_PIN_APP_3

public static final byte CVM_ETSI_PIN_APP_3

Indicates that the CVM interface required is the ETSI PIN App 3 (0x03).

Since:

export file version 1.5

See Also:

Constant Field Values

CVM_ETSI_PIN_APP_4

public static final byte CVM_ETSI_PIN_APP_4

Indicates that the CVM interface required is the ETSI PIN App 4 (0x04).

Since:

export file version 1.5

See Also:

Constant Field Values

CVM_ETSI_PIN_APP_5

public static final byte CVM_ETSI_PIN_APP_5

Indicates that the CVM interface required is the ETSI PIN App 5 (0x05).

Since:

export file version 1.5

See Also:

Constant Field Values

CVM_ETSI_PIN_APP_6

public static final byte CVM_ETSI_PIN_APP_6

Indicates that the CVM interface required is the ETSI PIN App 6 (0x06).

Since:

export file version 1.5

See Also:

Constant Field Values

CVM_ETSI_PIN_APP_7

public static final byte CVM_ETSI_PIN_APP_7

Indicates that the CVM interface required is the ETSI PIN App 7 (0x07).

Since:

export file version 1.5

See Also:

Constant Field Values

CVM_ETSI_PIN_APP_8

public static final byte CVM_ETSI_PIN_APP_8

Indicates that the CVM interface required is the ETSI PIN App 8 (0x08).

Since:

export file version 1.5

See Also:

Constant Field Values

APPLICATION_LOCKED

public static final byte APPLICATION_LOCKED

The current applet context is in the Life Cycle State of LOCKED (0x80). To know if an application is locked, a logical AND operation shall be performed between this constant and the current application life cycle state.

See Also:

Constant Field Values

FAMILY_SECURE_CHANNEL

public static final byte FAMILY_SECURE_CHANNEL

Indicates the family of the Secure Channel Global Service Identifier (0x81).

Since:

export file version 1.1

See Also:

Constant Field Values

FAMILY_CVM

public static final byte FAMILY_CVM

Indicates the family of the CVM Global Service Identifier (0x82).

Since:

export file version 1.1

See Also:

Constant Field Values

FAMILY_AUHTORITY

public static final byte FAMILY_AUHTORITY

Deprecated. Use FAMILY_AUTHORITY instead.

Since:

export file version 1.2

See Also:

Constant Field Values

FAMILY_AUTHORITY

public static final byte FAMILY_AUTHORITY

Indicates the family of the Authority Service Identifier (0x83).

Since:

export file version 1.2

See Also:

Constant Field Values

FAMILY_HTTP_ADMINISTRATION

public static final byte FAMILY_HTTP_ADMINISTRATION

Indicates the family of the HTTP Administration Service Identifier (0x84).

Since:

export file version 1.3

See Also:

Constant Field Values

FAMILY_HTTP_REPORT

public static final byte FAMILY_HTTP_REPORT

Indicates the family of the HTTP Report Service Identifier (0x85). Application is not requested to expose this service through getService(AID, short)

Since:

export file version 1.3

See Also:

Constant Field Values

FAMILY_USSM

public static final byte FAMILY_USSM

Indicates the family of the USSM Global Service Identifier (0xA0).

Since:

export file version 1.1

See Also:

Constant Field Values

GLOBAL_SERVICE_IDENTIFIER

public static final byte GLOBAL_SERVICE_IDENTIFIER

Indicates the generic Global Service Identifier (0x80).

Since:

export file version 1.1

See Also:

Constant Field Values

Constructor Detail

GPSystem

public GPSystem()

Method Detail

getCardContentState

public static byte getCardContentState()

This method returns the Life Cycle State of the current applet context.

Notes:

• The OPEN locates the entry of the current applet context in the Open Platform Registry and retrieves the Life Cycle State.

Returns:

the Life Cycle State of the current applet context.

See Also:

APPLICATION_INSTALLED, APPLICATION_SELECTABLE, SECURITY_DOMAIN_PERSONALIZED

getCardState

public static byte getCardState()

This method returns the Life Cycle State of the card.

Returns:

the Life Cycle State of the card

See Also:

CARD_OP_READY, CARD_INITIALIZED, CARD_SECURED, CARD_LOCKED, CARD_TERMINATED

getCVM

public static CVM getCVM(byte bCVMIdentifier)

This method returns a handle to the CVM interface.

Notes:

• OPEN searches the GlobalPlatform Registry for the CVM Application that has the Global Service privilege and is uniquely registered with FAMILY_CVM and this bCVMIdentifier or is uniquely registered for the entire FAMILY_CVM;
• OPEN invokes the Applet.getShareableInterfaceObject() method of the corresponding CVM Application . OPEN provides the following parameters to the Applet.getShareableInterfaceObject() method: ‘clientAID’ is set to the AID of the current applet context (i.e. the requesting on-card entity) and ‘parameter’ is set to GLOBAL_SERVICE_IDENTIFIER;
• The CVM Application returns the reference of the Shareable Interface Object implementing the GlobalService interface. OPEN invokes the GlobalService.getServiceInterface() method with the following parameters: ‘GPRegistryEntry’ is set to the GPRegistryEntry interface of the current applet context (i.e. the requesting on-card entity), ‘sServiceName’ first byte is set to FAMILY_CVM and second byte to bCVMIdentifier, baBuffer is set to null (indicating no buffer), sOffset and sLength are set to zero;
• The CVM Application returns the reference of the Shareable Interface Object implementing the CVM interface corresponding to bCVMIdentifier. This handle is then returned by OPEN to the requesting applet.

Parameters:

bCVMIdentifier - identifies the required CVM interface.

Returns:

the CVM interface object reference. null if there is no matching CVM Interface in the GlobalPlatform Registry.

See Also:

CVM_GLOBAL_PIN

getSecureChannel

public static SecureChannel getSecureChannel()

This method returns a handle to the SecureChannel interface.

Notes:

• The OPEN locates the entry of the current applet context in the Open Platform Registry to determine the application's associated Security Domain,
• This method may be implemented using a similar mechanism as described for the getCVM method.

Returns:

the SecureChannel interface object reference.

lockCard

public static boolean lockCard()

This method locks the card.

Notes:

• The OPEN locates the entry of the current applet context in the Open Platform Registry and verifies that the application has the card lock privilege.

Returns:

true if card locked, false otherwise

terminateCard

public static boolean terminateCard()

This method terminates the card.

Notes:

• This method shall not be invoked from the Applet.install() method.
• The OPEN locates the entry of the current applet context in the Open Platform Registry and verifies that the application has the card terminate privilege.

Returns:

true if card terminated, false otherwise.

setATRHistBytes

public static boolean setATRHistBytes(byte[] baBuffer,
                                      short sOffset,
                                      byte bLength)

This method sets the historical bytes of the ATR (Answer To Reset) string. The sequence of bytes will be visible on a subsequent power-up or cold reset.

Notes:

• The OPEN locates the entry of the current applet context in the Open Platform Registry and verifies that the application has the "Card Reset" privilege for the current card I/O interface;
• The OPEN is responsible for synchronizing the length of historical bytes in Format Character T0 of the ATR.

Parameters:

baBuffer - the source byte array containing the ATR historical bytes.

sOffset - offset of the ATR historical bytes within source byte array.

bLength - the number of historical bytes.

Returns:

true if ATR bytes set, false otherwise.

setCardContentState

public static boolean setCardContentState(byte bState)

This method allows the application associated with the current applet context to change its state to an application specific life cycle state or to lock itself. An application cannot unlock itself using this method.

Parameters:

bState - an application specific life cycle state (0x07 to 0x7F with 3 low order bits set), or APPLICATION_LOCKED (0x80).

Returns:

false if the application invoking this method is currently locked.

Since:

• export file version 1.0: initial version.
• export file version 1.5: this method now allows the application associated with the current applet context to lock itself.

getRegistryEntry

public static GPRegistryEntry getRegistryEntry(javacard.framework.AID reqAID)

This method allows an Application (e.g. a CVM) to access the GP Registry entry of another Application. If no AID is input, this method provides the GP Registry entry of the requesting Application. It returns a handle to the GPRegistryEntry interface.

Notes:

• The OPEN verifies that the requesting Application has the Global Registry privilege, or is the Security Domain associated with the Application being investigated, or is the investigated Application itself.

Parameters:

reqAID - identifies the required GPRegistryEntry interface.

Returns:

The GPRegistryEntry interface reference corresponding to the input AID, or null if there is no Application in the GP Registry that corresponds to the input AID or if the requesting Application is not authorized to access the corresponding GP Registry entry.

Since:

export file version 1.1

See Also:

AID

getService

public static GlobalService getService(javacard.framework.AID serverAID,
                                       short sServiceName)

This method returns a handle to the Global Services interface of a Global Services Application.

Notes:

• The serverAID parameter is optional: if not known by the requesting on-card entity, it is set to null;
• The sServiceName parameter is mandatory. When the serverAID is Null, the OPEN searches the GlobalPlatform Registry for the Global Services Application corresponding to this unique sServiceName or to this entire service family. When the serverAID is not null, the OPEN checks that the sServiceName or to this entire service family is recorded in the GP Registry for this serverAID;
• OPEN invokes the Applet.getShareableInterfaceObject() method of the corresponding Global Services Application. OPEN provides the following parameters to the Applet.getShareableInterfaceObject() method: clientAID is set to the AID of the current applet context (i.e. the requesting on-card entity) and parameter is set to GLOBAL_SERVICE_IDENTIFIER;
• The Global Services Application returns the reference of the Shareable Interface Object implementing the GlobalService interface. This handle to the GlobalService interface is then returned by OPEN to the requesting applet.

Parameters:

serverAID - identifies the required Global Service Application AID or is null.

sServiceName - identifies the required Global Service Service Name or the entire Service Family.

Returns:

the GlobalService interface object reference or null.

Since:

export file version 1.1

See Also:

GLOBAL_SERVICE_IDENTIFIER, FAMILY_CVM, FAMILY_SECURE_CHANNEL, FAMILY_USSM, FAMILY_AUTHORITY, FAMILY_HTTP_ADMINISTRATION, FAMILY_HTTP_REPORT